\input texinfo   @c -*-texinfo-*-
@smallbook
@c
@c **last updated**: Dec 10, 1987
@c
@setfilename gulam.info
@settitle Gulam

@titlepage
@sp 10
@center @titlefont{A Reference Manual for}
@sp 1
@center @titlefont{Gul@"am}
@sp 3
@center Prabhaker Mateti
@center Department of Computer Engineering and Science
@center Case Western Reserve University
@center Cleveland, Ohio 44106
@sp 3
@center Copyright @copyright{} 1987 Prabhaker Mateti
@sp 5
@center pm@@mandrill.cwru.edu
@center December 1987
@end titlepage

@node top, usage, , (DIR)
@unnumberedsec Introduction

@emph{Gul@"am} is a shell (i.e., a command line interpreter) for AtariST
computers.  It contains some 60+ built-in commands, provides file name
completion a la @emph{TENEX}, has history, alias and rehash
facilities, and integrates the shell with microEmacs easing the
editing of commands being issued.  Among the built-in commands are

@table @code
@item egrep
a regular expression based string  pattern  finder.
@item te
a simple terminal emulator.
@item rx/sx
Xmodem  file  transfers
@item pr
a text file printer with pagination.
@end table

In common usage, it resembles @emph{csh} of @emph{Unix 4.xBSD};
Gul@"am's control structures, lexical conventions and other details are,
however, quite different from csh.  While I have borrowed ideas from
other shells (such as Korn shell), I made no heroic attempts to be
compatible with any.  Where possible, I have tried to make
@emph{Gul@"am} less `surprising' in what it does.

The word @emph{Gul@"am} is pronounced as @emph{Gulaam} in Hindi/Urdu,
and means an obedient servant.

@emph{Gul@"am} is a free program; you are encouraged to give it to others,
but at no cost.  However, the source is copyrighted (i.e., it is not in the
public domain) and will be part of a book on systems programming I am
writing.  The source is available on request, with the usual provisos
regarding material in manuscript form.  This manual is written in the
@emph{TeXinfo} format (the @emph{GNU} documentation format); a laser-printed
@TeX{}-typeset copy of this 40-page manual is also available at cost ($2.00).

I am advised to include a disclaimer because there are unreasonable people
out there.

``I make no warranty with respect to this manual, or the program it
describes, and disclaim any implied/explicit suggestions of usefulness for
any particular purpose.  Use this program only if you are willing to assume
all risks, and damages, if any, arising as a result, even if it is caused
by negligence or other fault.''

The first release of this program did contain bugs.  The present
beta-version (dated Sept 1987) is a result of fixing 15 bugs, 9 internal
code improvements (about 180 lines of rewriting), 9 user-visible
improvements.  I am sure this version too has bugs, and undesirable
features.  Users are encouraged to tell me both good and bad things about
this program.


Many thanks to: Jwahar R.  Bammi for help in every aspect during the
writing of the shell and this manual, and demanding that
@emph{Gul@"am} be a `reasonably full fledged' shell; David Conroy for
writing a `small is beautiful' microEmacs; Henry Spencer for the
regexp(3) package that is now built into @emph{Gul@"am}; AtariST for
its value to price ratio.  The program was developed using Megamax and
Mark Williams C compilers.  It now uses my own malloc.c.


@unnumberedsec Comments on the Present Implementation

I find the present implementation eminently useable, and indeed use it
all the time, in preference to other shells.

Here are some features that I (still) find unsatisfactory.  Control
structures are quite ad-hoc, and incomplete.  I had a tough time in
decreeing that the typical @samp{+-*/()[]@{@}} are not delimiters; but
that decision made @emph{Gul@"am} smaller.

Here is a list (complete?) of things new and/or diffrent from the
alpha-version.

@enumerate
@item
the bugs causing memory-lossage have been fixed.
@item
an application program can now call one of @emph{Gul@"am}'s routines
that is equivalent to system() call.
@item
an application program can now call one of @emph{Gul@"am}'s routines
that can receive keyboard input from the user, with all the facilities of
@code{ue}, and return the line input by the user.
@item
@code{ue} can now insert-file.
@item
stdout append-redirection (@code{>>}) is now implemented.
@item
a new sub-word consisting of three dots @code{...} expands to the list
of all filenames rooted at the current or given directory.
@item
doing a @code{set path <path-list>} will also cause an automatic
@code{setenv PATH <path-list> ; rehash}.
@item
@code{ue} can now fill-paragraph.
@item
new shell variable `verbosity' controls how silent @emph{Gul@"am} is.
@item
cp will not copy directories and their contents unless
given the @code{-r} flag.
@item
@code{ue} can now use mouse movements as cursor
movements (see mscursor).
@item
diskettes can be formatted (single/double-sided) in TOS standard way.
@item
the command mem can not only report the GEMDOS free-list but also the list
of GEMDOS Malloc-ated chunks.
@item
shaded background on the screen is provided for the @code{gem} command.
@item
the keypad keys can be toggled to become numeric
or extra-function keys.
@item
there are 3 separate key-bindings for the one @emph{gul@"am} buffer, and
the one @emph{mini} buffer, and all the regular buffers.
@end enumerate

@node usage,lexical-conventions,top,top
@unnumberedsec General Usage

The syntactic details of individual commands, and the specific rules that
are followed in evaluating them are given later.  This section is an
overview of how the integration of @code{ue} with a shell is used.

The moment you enter @emph{Gul@"am}, you are in a ue-buffer
called @emph{mini}.  Thus, all the typical @code{ue} text-editing
functions are available, except commands such as @code{Visit-file},
@code{Switch-to-buffer}, etc.  The @kbd{RETURN} key causes the entire
line (on which the return is typed) to be evaluated.  The output, if
any, of the command you issued appears on the screen but does not
enter any ue-buffer.  The built-in command @code{ue} (without any
arguments) takes you into the special ue-buffer named @emph{gul@"am};
the output of (built-in) commands issued while you are in @emph{gul@"am}
does enter that buffer, which can be freely edited.  The command
@code{ue} @var{filename} will read-in each of the named files into
their ue-buffers.  From within @code{ue}, you can
@code{Switch-to-Gulam-buffer} (whose default binding is @kbd{ESC-g}).

To conserve/manage memory, we release all @code{ue} buffers when @code{ue}
is exited in the usual way (i.e., @kbd{UNDO}, or @kbd{@ctrl{X}-@ctrl{C}});
exiting temporarily via the @kbd{@ctrl{Z}} does not release memory.
Issuing a substantial number of commands through the @emph{mini} buffer,
without entering @code{ue} in between, will accumulate all the commands
(but not their output) in the @emph{mini} buffer, and soon there will be a
memory shortage.  To prevent this, enter and exit @code{ue} once in a
while, or delete (using @kbd{@ctrl{D}}, or @kbd{Delete}) characters in the
@emph{mini} buffer.



@node lexical-conventions,command-processing,usage,top
@unnumberedsec Lexical Conventions

All  input  to  @emph{Gul@"am}  is  case-sensitive; on the other hand, TOS
file names are case-independent.  

The  evaluation  of  the command line  begins by dividing it into
@dfn{words} and @dfn{subwords}.  The @dfn{word-delimiters} are
space, tab, return, line-feed (the so-called white chars),
single-quote, double-quote, semicolon, and the vertical-bar.


Note that  @code{+-*=/()[]@{@}} etc. are @emph{not} @dfn{word-delimiters}.  A
@dfn{word}  is  either

@itemize @bullet
@item
A  sequence  of  chars  not containing any @dfn{word-delimiters}.
@item
A  string  of  arbitrary chars enclosed in single/double-quotes.
@item
A @kbd{semicolon}.
@item
A @kbd{vertical-bar}.  
@end itemize

Eg,  the lines below 

@example
date  01-22-87-22:08:34  #sets the TOS and ikbd date-time
alias c 'mmcc e:\gulam\$1.c; cp e:\gulam\$1.o .'
if    @{$x + $y ==23 @}
if    @{ -e $1.c @}
@end example

would be divided into the words (shown between slashes) 

@example
/date/01-22-87-22:08:34/#sets/the/TOS/and/ikbd/date-time/
/alias/c/'mmcc e:\gulam\$1.c; cp e:\gulam\$1.o .'/
/if/@{$x/+/$y/==23/@}/
/if/@{/-e/$1.c/@}/
@end example

@dfn{Comments} begin  with  a  word  whose first char is @kbd{#}, and
end  at  the  end  of line.  A @kbd{#} embedded in the middle of a word
does not begin a comment.  

The @dfn{subword-delimiters} are the characters in @*
@code{!@@#$%^&-=+`~@{@}:;'"\|,.<>/}.

@node command-processing,batch-files,lexical-conventions,top
@unnumberedsec Outline of Command Processing

The command line is string pre-processed as described below before invoking
it as a command.

@itemize @bullet
@item
History substitutions occur first.
@item
Dollar substitutions, wiggle  expansion,  meta  expansions  occur second.
@item
Split the resulting  line  into semi-colon separated commands.
@item
For each command,  alias  expand  it,  and  dollar-substitute.
@item
Execute each resulting command.  
@end itemize

@node batch-files,buffers,command-processing,top
@unnumberedsec Batch Files

A @dfn{batch file}, also called a shell file, is a text file containing
@emph{Gul@"am} commands, both internal and external.  Such files must have
the extension @code{.g} for them to be recognized as commands.  See the
section on @code{gulam.g} for an example shell file.

In processing these files @emph{Gul@"am} uses @code{ue} buffers.  So, if
you have @code{ue} as a command in a batch file, and then exit @code{ue}
with either @kbd{UNDO} or @kbd{@ctrl{X}-@ctrl{C}}, all the buffers
(including the one holding the batch file) will be released, and
@emph{Gul@"am} will surely crash. So, do @emph{NOT} include @code{ue} as a
command in a shell file.

Redirections to/from batch files do not work properly.

@node buffers,command-line-editing,batch-files,top
@unnumberedsec Buffers: Gulam, Mini and Regular Buffers

Once you invoke @emph{Gul@"am}, you are always in one of the microEmacs
(@emph{uE}) @dfn{buffers} which are reservoirs of text.  In this program, a
typical line-oriented command shell is integrated with microEmacs.  This
necessitated two special kinds of buffers, named @emph{gul@"am} and
@emph{mini}, along with the regular buffers.

Right after you invoke @emph{Gul@"am}, you are in @emph{mini}, and each
line you type is taken as a @emph{Gul@"am} command, and executed.  Any
output produced by such a command is displayed on the screen but not
entered into any microEmacs buffer.  Should you desire to capture such
output into a buffer, enter the @emph{gul@"am} buffer by typing @code{ue}
without any arguments.  If you are editing in a regular buffer elsewhere in
microEmacs, pressing @kbd{ESC-g} (see @code{kb} below for
@code{switch-to-Gulam-buffer}) will get you into @emph{gul@"am}.

While you are in @emph{Gul@"am}, the @kbd{RETURN} key behaves as it does in
@emph{mini}.  All command input, including giving the names of buffers
within @code{ue}, takes place in @emph{mini}.  The window for this buffer
is always at the bottom of screen, and usually only one-line high.  (Some
of you may want to experiment with @kbd{@ctrl{X}-@ctrl{Z}} and
@kbd{@ctrl{X}-z}.) You enter the @emph{mini} either because (A) you are
outside the normal microEmacs, or (B) a command such as
@code{Switch-to-buffer} wants to read your input.  The @emph{mini} is like
any other buffer except for the bindings of a few keys, and the disallowing
of @code{ue} functions that change/switch buffers/windows/files.  One of
these exceptional keys (in @emph{mini}) is the @kbd{RETURN} key: it will
submit the entire line -- even if the cursor was somewhere in the middle of
the line-- to the shell (case A), or to such @code{ue} commands as
@code{Visit-File} (case B).  Until you press @kbd{RETURN}, you can edit not
only that line but others in @emph{mini} just as you would in regular
buffers.

Note that unless you occasionally exit microEmacs with
@kbd{@ctrl{X}-@ctrl{C}} or @kbd{UNDO}, both @emph{gul@"am} and @emph{mini}
buffers will keep growing, and you may run out of memory.

@node command-line-editing,invoking-gulam,buffers,top
@unnumberedsec Command Line Editing

Full microEmacs editing is available while typing the command.  Thus, you
can transopse chars by @kbd{@ctrl{T}}, and go to the beginning of the line
by @kbd{@ctrl{A}}, and @ctrl{Y}ank in a perviously deleted word, etc.

In addition to these, there are three convenience features.  After typing
the first few chars of a file name, if you press the key marked
@kbd{INSERT}, @emph{Gul@"am} will attempt to complete the file name;
pressing @kbd{CLR/HOME} will show all possible completions.  Secondly, if
you type @code{!n} and then press @kbd{INSERT}, you will see that the
history-expanded result is brought into the buffer, which can then be
further edited if necessary.  Thirdly, pressing the @kbd{DOWNARROW} key
will cycle you through the previous commands.


@node invoking-gulam,Glossary,command-line-editing,top
@unnumberedsec Invoking Gulam

@emph{Gul@"am} can be used in four ways.  Two of these four use @code{TOS}
variable named @code{_shell_p} (at @code{0x04f6L}).  This (supposedly)
contains a pointer to a routine that takes a string as an argument and
executes it as a shell command.  @emph{Gul@"am} has slightly extented this.
@code{*_shell_p}, as set by @emph{Gul@"am}, points the bottom of a (jump)
table, which currently is:

@example
        .long   0x86420135        / our magic number
        jmp     getlineviaue_
togu_:  jmp     callgulam_
@end example

Thus, @code{*((long *) 0x04f6L)} == address of @code{togu_}.  Before
invoking either routine, it always is a good idea to check if the magic
number is present.  Let @code{mp = *((long *) 0x04f6L) - 12L}.  Then,
@code{*mp} better be @code{0x86420135}.

@enumerate
@item
The most common usage is as an (outermost) interactive shell.
Double-click on @code{gulam.prg}.  Keep your version of @code{gulam.g} also
in the same folder.
@item
@code{int callgulam(p) char *p;} returns the status of executing
shell command given as a string pointed by @code{p}.  Let @code{fp =
*((long *) 0x04f6L)}.  Then to call this routine, you do @code{(*fp)(p)}.
@item
@code{void getlineviaue(p) char *p;} returns in the user-supplied
array of chars pointed by @code{p} the command line typed by the user.  Full
uE editing facilities are available in this inputting process.  @code{p} must
point to an array of at least 256 chars; longer input lines cannot be
given.  The line may contain control characters (inserted by the ^Q
feature of @code{ue}).  It is ascii NUL terminated.  Let @code{fp = *((long *)
0x04f6L) - 6L}.  Then to call this routine, you do @code{(*fp)(p)}.
@item
For non-interactive use, @emph{Gul@"am} can be invoked (from shells, from
application programs via @code{Pexec()}, or @code{callgulam()}) with arguments.
@end enumerate

@code{gu 'ls -l' 'echo hello'} is similar to typing the two commands to the
shell in interactive mode.

@code{gu 'pwd' -c scrpt a b c d} does @code{pwd}, and then invokes the
(presumably valid) @emph{Gul@"am} shell script named @code{scrpt.g} with
@code{a b c d} as the script files arguments.  Following the @code{-c}
must be the name of a batch file.

@emph{Gul@"am} has no other options.

@node Glossary,top,invoking-gulam,top
@unnumberedsec Glossary

@findex builtins
@node builtins,cd,Glossary,Glossary

@unnumberedsubsec Builtin Commands

A command executed directly by the shell is called a @dfn{built-in}
command.  The 62 built-in commands of @emph{Gul@"am} are:

@example
alias dm     endwhile help    more  printenv set    ue
cat   dirc   exit     history mson  pushd    setenv unalias
cd    dirs   fg       if      msoff pwd      source unset
chmod echo   fgrep    kb      mv    rehash   sx     unsetenv
copy  egrep  foreach  lpr     peekw ren      te     which
cp    ef     format   ls      pokew rm       teexit while
date  endfor gem      mem     popd  rmdir    time
df    endif  grep     mkdir   print rx       touch
@end example

@findex alias
@node alias,cat,Glossary,Glossary
@unnumberedsubsec alias

The @code{alias} built-in command works almost like a shell file but one
that is stored in the internal data structures of @emph{Gul@"am}.  It often
just specifies a shorter or different name for a command.

@example
alias cc c:\megamax\mmcc.ttp    #1
unalias cc                      #2
alias c 'mmcc e:\gulam\$1.c; cp e:\gulam\$1.o .' #3
alias r  'echo $1.c $1.o; r'    #4
alias                           #5
alias g 'echo $3 $1'            #6
alias cg 'f:\cc.ttp -c -Ie:\gulam -DMWC e:\gulam\$1.c' #7
@end example

Alias without args (see #5) lists all the aliases that are currently
defined.  The command unalias (see 2) removes the def of an alias.  Line 4
shows a recursive definition; try it out!  If we invoke @code{g} as in
@code{g a b c d e f} this is equivalent to @code{echo c a d e f}; i.e., all
arguments above the highest that was used in a @dfn{$-substitution} are
appended to the resulting command string before executing it.

@findex cat
@node cat,cd,alias,Glossary
@unnumberedsubsec cat

This command `catenates' files to the standard output (normally screen).
By redirecting output, you can concatenate several files into a combined
file.

@example
cat f1 f2 >f3	# f3 will now equal f1 followed by f2
cat f1 > prn:	# print the file f1 as is; see also print and lpr
cat f1		# show it on the screen; use ^S/^Q to stop/go
@end example

@findex cd
@node cd,chmod,cat,Glossary
@unnumberedsubsec cd

The @code{cd} command changes the current working directory; it also sets
the shell variable named @code{cwd}, the environment variable
named  @code{CWD}.  If @code{cd} was given noarguments,  it is equivalent
to @code{cd $home}.

@findex chmod
@node chmod,cp,cd,Glossary
@unnumberedsubsec chmod
@example
chmod [+-whsvm] @var{filenames}
@end example

@code{chmod} changes the read/write attributes of the files.  The
@code{+} flags have inverse effect to the @code{-} flags.  The @code{+w}
makes them read-write, and @code{-w} makes them read-only.  The
@code{+h} hides the files from directory searches; @code{+s} marks
them as hidden system files; @code{-m} turns off the `archived' flag
on the file.


@findex cp
@node cp,date,chmod,Glossary
@unnumberedsubsec cp
@example
cp @var{filenames target-dir}
cp @var{filename1 filename2}
@end example

Copies files.  In the first form, any number of files may be copied into
the destination directory; files in the target dir will have their original
names.  In the second form, only one file is copied, and the new one will
be named filename2.

@example
cp @var{fnm fnm}    # will exit with status -1 
cp -r @var{d1 dir2}     # if d1 is a directory, this command
              # will create a dir named d1 in dir2, and 
              # copies all the files in d1 to to dir2\d1 
@end example

In the second example above, if -r option is omitted, cp will ignore any
directory names in the list of source files.  Use the -r option with
caution.  E.g.,

@example
cp -r d1  d1\d2 # is dangerous 
@end example

will, assuming that d1\d2 is a directory, copy/create subtree d1 inside d2.
But, the problem is that d1 will keep growing as a result until of course
there is no more room on the target disk!

A simple way to print a file as is, instead of using lpr or print, is to

@example
cp fnm prn: 
@end example

There is a @code{+t} option that gives the created target files the time
and date of the source files.  If you care about this, you may want to set
up an @code{alias} as in:

@example
alias cp 'cp +t' 
@end example

@vindex cwd
@vindex CWD
@unnumberedsubsec $cwd and $CWD

The shell variable named @code{cwd} (and env var named @code{CWD}) holds the
full path name of the current working directory.  

@findex date
@node date,df,cp,Glossary
@unnumberedsubsec date

The @code{date} command, without arguments, prints the current date and
time.  With arguments, it sets the date and time.  

@example
date 01-22-87-22:08:34 
@end example

will set the date to Jan 22, 87 and time to 10:08:34 pm.  Instead of hyphen,
and colon, other delimiters can be used, as long as the whole argument of date
is still one word.

@findex df
@node df,dm,date,Glossary
@unnumberedsubsec df
@example
df @var{drivenames}
@end example

@code{df}  shows the free space on the asked for drive(s); e.g.,
@example
df a c f
@end example

@findex dm
@node dm,dirc,df,Glossary
@unnumberedsubsec dm

@code{dm} (drive map) gives a string of letters that stand for the
installed drives.

@findex dir_cache
@findex dirc
@node dirc,dirs,dm,Glossary
@unnumberedsubsec dir cache dirc

To help do the Tenex file name completion efficiently, there is a
cache of contents of directories.  @code{dirc} shows the names of
these dirs, and how many bytes are used by their contents.  Unless you
did a @code{set dir_cache 1}, or you executed commands that only
examine the file system the @code{dirc} has nothing to show since the
cache is flushed at the end of each command.  Try @emph{Gul@"am} with
@code{dir_cache} set to 1.  Note however that this cache is updated
only by commands that change the contents of a directory (such as
@code{rm}, @code{cp}).  A rather annoying result is that even after
you change the diskette in a drive, you may see the directory contents
of the previous diskette listed.  An @kbd{UNDO}, @code{dirc -},
@code{rm} with/without arguments will explicitly flush the cache.

@findex dirs
@node dirs,echo,dirc,Glossary
@unnumberedsubsec dirs

@emph{Gul@"am} has an internal stack of directories whose content is
printed by the @code{dirs} command.  The built-in commands @code{pushd},
and @code{popd} are the only others that operate on this stack.

@node dollar-substitutions,expressions,command-line-editing,top
@unnumberedsubsec Dollar-substitutions

The subword @code{$x} in a command is substituted by the value of it.  If
@code{x} is the name of a shell var, or an environment var, then @code{$x}
is the value of that variable.  If @code{x} is an unsigned number, it
stands for the x-th argument; thus, @code{$0} usually gives the command
name.   @code{$*}  stands  for the text of the entire command; @code{$-} stands
for  words  @code{$1}  to dollar-last; @code{$<} stands for the on-demand input
given by the user.  


@unnumberedsubsec Dotg.g

-- see Batch Files, and gulam.g 

@findex echo
@node echo,ef,dirs,Glossary
@unnumberedsubsec echo

The @code{echo} command prints its arguments.  

@example
echo c:\mwc\...	# all the fnms in the dir tree rooted at c:\mwc will be echoed
@end example

@findex ef
@node ef,egrep,echo,Glossary
@unnumberedsubsec ef
-- stands for @code{elseif}; see @code{if}

@findex egrep
@node egrep,endif,ef,Glossary
@unnumberedsubsec egrep
-- see @code{grep}

@findex endif
@node endif,endfor,egrep,Glossary
@unnumberedsubsec endif
-- see @code{if}

@findex endfor
@node endfor,exit,endif,Glossary
@unnumberedsubsec endfor
-- see foreach

@vindex env_style
@unnumberedsubsec Style of Environment String 

This shell var controls the format of the environment string supplied to
the external command invoked through @emph{Gul@"am}.

@example
set env_style bm # to get a style of env a la MS-DOS
set env_style mw # Mark Williams
set env_style gu # the "normal" style, a la Unix
@end example

@findex exit
@node exit,fg,endfor,Glossary
@unnumberedsubsec exit
@example
exit [@var{number}]
@end example

The @code{exit} built-in command is used to force termination of a shell
script.

@node expressions,flags,dollar-substitutions,top
@unnumberedsubsec Expressions 

An @dfn{atomic exp} is either a @var{number}, a @var{filename}, a @var{file
predicate}, a @var{@{ exp @}}, or @var{! atomic exp}.

A @var{file predicate} on a file name @var{fnm} is of the form @code{-c
@var{fnm}} where @code{c} is in @code{@{e, f, d, h, v, m@}}.  These letters
stand for @dfn{exists}, @dfn{is-a-regular-file}, @dfn{is-a-dir},
@dfn{is-a-hidden-file}, @dfn{is-a-volume-label}, and
@dfn{is-an-archived-file}.  A @var{filepred} yields 1 if it is true, 0
otherwise.

An arithmetic expression is constructed using the operators @code{+-/%*}.
All these are of equal precedence and evaluated left-to-right; thus,
@code{2 + 4 / 2} is equal to 3.  However, the braces raise the precedence
of the ops within them; thus, @code{2 + @{ 6 / 2@}} is equal to 5.  An exp
with no operators, i.e., an atom, is a special case because we want the
string form of the atom (e.g., as for @code{blah} in @code{set s blah}).  A
non-numeric string yields 0 as its numeric value in an arith exp.

A @dfn{relational expression} is of the form @code{arithexp relation
arithexp}, where relation is any one of @code{<=, <, ==, !=, >,} or
@code{>=}.  Such a relation yields a 1 if it holds, 0 otherwise.
(Relational operators among strings are not implemented yet.)  You may
combine expressions using the boolean operators @code{&&} and @code{||}
(which are not, for now, short-circuit evaluated).

Note the spaces in the examples above; see Lexical Structure.  

@findex fg
@node fg,file-names,exit,Glossary
@unnumberedsubsec fg

@code{fg} is part of the simulation of what we were used to doing on Unix
with GNU-Emacs: get out of it by stopping GNU (@kbd{@ctrl{Z}} in ue/Gulam),
do a few shell commands and get back in by @code{fg} (works the same in
ue/Gulam).


@findex file-names
@node file-names,foreach,fg,Glossary
@unnumberedsubsec File Names

There are many conveniences in @emph{Gul@"am} that relate to specifying
filenames.  It can complete a file name given its first few characters.
(Tenex is widely considered to be the first OS to implement this.) Type the
first few characters, and then press the key marked @kbd{INSERT} (or
@kbd{CLR/HOME}), while you are in @emph{mini}.  If you are in buffer
@emph{gul@"am}, use @kbd{ESC} @kbd{ESC} (2 escapes).

The canonical form of the full path name of a file begins with a letter
designating the disk drive, followed by a colon, a back-slash separated
list of identifiers.  All but the last of these identifiers must be a
directory name.  In the non-standard form, you may also use a dot `.', and
dot-dot `..' in place of the identifiers in appropriate contexts.  Whenever
@emph{Gul@"am} completes your filenames, it will produce the standard form
full path names.

@emph{Gul@"am} will standardize, in three situations, non-standard form of
a `path', as shown in the example below.  These situations are:
@enumerate
@item
Tenex file name expansion is invoked.
@item
the word contains meta characters.
@item
the name is being given to one of the file operations in @code{ue}.
@end enumerate

@noindent
@code{e:\gulam\a:\lex.c} is standardized to @code{a:\lex.c}@*
@code{e:\gulam\\src\util.c} is standardized to @code{c:\src\util.c}@*
@code{e:\gulam\~\ex.o} is standardized to @code{d:\bin\ex.c}@*

assuming that the current drive was @code{c:\}, and home was @code{d:\bin}, and
variable @code{parent_expand} is set.  This is especially nice inside
@code{ue} when visiting other files.

Words, as given by the you, that contain meta characters (which are
@code{*?|()[]}) or the string @code{...} are expanded.  In general, one
such word produces a list of file names.  These file name regular
expressions (fnmre) are like regular expressions (re), but have different
semantics.  Occurrences of an fnmre, outside of strings, are replaced by
the sorted blank-separated list of file names matching the fnmre.  An fnmre
differs from re in (1) `.' stands for itself; (2) `*' is matches zero or
more arbitrary characters.  Question mark matches any one character.
`[a-g]' matches any one letter in a, b, ..., g.  `[zen]' matches one of z,
e, or n.  Parentheses serve to group expressions.  An exp `g*' matches file
names that begin with a `g'; `*.c' matches those ending in `.c'

The 3 dots, as in @code{c:\tex\...}, stand for all the names
of the files in the subtree at @code{c:\tex}.  If @code{c:\tex} has
subdirectories, and so on, all their names and files they contain are
included.  Thus, @code{echo e:\...\*.c} will show all the @code{.c}
files in all the directories on drive e.  Remember that @code{...}
expansion causes many directories to be visited.  This is not only
time consuming, but also seems to trigger the Atari TOS's 40 folder
bug after a few such operations.  (In my tests, I never lost a file as
a result.  Nor can I tell precisely when and in what form this shows
up.  Most frequent indication was that @code{cd} to an existing drive
would fail.)

@node flags,history-substitutions,expressions,top
@unnumberedsubsec Flags

Most commands (built-in or external) take flags to alter the behavior of
the command in a minor way.  The convention made popular by Unix shells is
adopted here for @emph{Gul@"am}'s built-ins: a flag is of the form
@code{-@var{c}}, or @code{+@var{c}}, where @var{c} stands for one
character.  The option @code{-i}, which interrogates you for each of the
operand of the command before executing it, is provided on most commands.

@findex foreach
@node foreach,format,file-names,Glossary
@unnumberedsubsec foreach

The @code{foreach} command is used in shell scripts (but not at the
terminal) to specify repetition of a sequence of commands while the value
of a certain shell variable ranges through a specified list.  The
@code{foreach} command ends with an @code{endfor} on a separate line all by
itself.

@example
foreach i @{ a b c *.o [a-k]*[ch] @} 
        echo $i 
endfor 
@end example

@findex format
@node format,gem,foreach,Glossary
@unnumberedsubsec format

This command formats diskettes, in the standard form (360K, or 720K) in
either the @code{A} or @code{B} floppy drive.  It does not touch
hard-/ram-disks, no matter what arguments (illegal or not) you give it.
Its valid arguments are either @code{a}, @code{b}, or both.  The optional
flag @code{-2} implies double-sided formatting; otherwise the diskette is
formatted single-sided.

@example
format        # does nothing 
format b      # format the floppy in dr B, single-sided 
format -1 b   # same as format b 
format -2 a   # format the floppy in dr A, double-sided 
@end example

If you issue the wrong command (e.g., @code{format -2 a} on a single-sided
drive), you will hear a lot of grinding noises; a @kbd{control-C} will kill
this, but not right away.

@findex gem
@node gem,grep,format,Glossary
@unnumberedsubsec gem

The word @code{gem} is a prefix, like @code{time} is, to commands.  This
enables proper running via @emph{Gul@"am} of most programs that use the
desktop metaphor.  It clears screen, turns cursor off, enables mouse and
then executes the command, and after the command is finished it again
clears screen, turns cursor on, disables mouse.

The @code{time} and @code{gem} prefixes mix in either order, and the
command name will be searched for in the usual way.

We do not know, for sure, if all desktop/window/mouse oriented programs can
be run properly with this command prefix.  So experiment, and be ready to
hit the reset button before using the prefix.

@code{dvi} is an example of a command that needs to be run with @code{gem}
prefix.  And you may be tempted to do the following.

@example
alias dvi 'gem dvi'              # recurses infinitely 
alias dzz dvi                    # dzz or whatever 
alias dvi 'gem dzz'              # will work 
alias dvi 'gem c:\bin\dvi.prg'   # also will work 
@end example

@findex grep
@findex egrep
@findex fgrep
@node grep,gulam.g,gem,Glossary
@unnumberedsubsec grep/egrep/fgrep
@example
grep/egrep/fgrep @var{re-pattern filenames}
@end example

The @code{grep} command searches through a list of argument files for a
specified string.  Thus

@example
grep lex[aw] e:\gulam\*.c 
@end example

will print each line in the files that contains a substring matching
@code{lex[aw]}. @code{grep} stands for ``globally find regular expression
matches and print''. @code{grep} and @code{egrep} are one and the same.
The first argument to @code{egrep} is a regular expression, and the rest
are expected to be file names. @code{fgrep}'s first argument is the as-is
string to be searched for in the files.  Because of the preprocessing done
by @emph{Gul@"am}, the as-is string for @code{fgrep} or the regular exp for
@code{egrep} is generally enclosed in single-quotes.

@node gulam.g,help,grep,Glossary
@unnumberedsubsec gulam.g

Files with the @code{.g} extension are expected to contain @emph{Gul@"am}
commands; @code{gulam.g} is the name of the startup file.  @emph{Gul@"am}
attempts to find this file in the current directory, and if found executes
its contents.  Here is an example file:

@example
# bgn of my gulam.g

set prompt      '$ncmd $cwd gu > $u'
set histfile    e:\history.g
set baud_rate   9600
set sz_rs232_buffer     4096
# set palette; note the trailing '-'
set rgb '005-707-070-075-'
# the following sets tabs on Epson MX-80
set pr_bof '^Q033^QD^Q010^Q020^Q030^Q040^Q050^Q033^QC^Q102'
set pr_eof '^Q214'
set pr_eop '^Q214^Qn'
set pr_eol '^Qr^Qn'

#setenv PATH c:\bin,d:\bin,f: # no trailing back slashes
#rehash
set path c:\bin,d:\bin,f:     # equiv to above 2 lines
setenv TEMP f:\
alias h  history
alias ll 'ls -lF'
alias p  more
alias rm 'rm -i' # asks before deleting
alias ug 'ue e:\gulam\$1.c'
alias cg 'f:\cc.ttp -c -V -Ie:\gulam -DMWC e:\gulam\$1.c'
alias cpall 'cp e:\ue\*.o e:\gulam*.o f:\ '
alias bk 'cp e:\gulam\*.[chs] a:\ '
# end of my gulam.g
@end example

@unnumberedsubsec Gulam Variables and Environment

The following shell variables cause/control useful effects.  The format of
the explanation is `variable_name: default-value meaning'.

@table @code
@vindex batch_max_nesting
@item batch_max_nesting: 20
if you need to nest batch file execution at levels deeper than this,
change this variable.

@vindex batch_echo
@item batch_echo: 0
if  1  echoes each command of the batch file as it is executed.  

@vindex baud_rate
@item baud_rate: none
for  use  in  the  terminal  emulator, rx/sx file transfers.  

@vindex cwd
@vindex CWD
@item cwd:
@itemx CWD: full  pathname  of  current directory
gets re-set every time a cd, pushd or popd is executed.  

@vindex delay
@item delay: unset
set it to control the duration that the cursor sits
on a matching paren, bracket, or brace.  A value of 2000 produces about
a 2-sec delay.

@vindex dir_cache
@item dir_cache: 0
if non-0, turns on the dir list cache.  This substantially speeds up the
Tenex file name completion.

@vindex ginprompt
@item ginprompt: $<
the  prompt  shown  when  asking you for input in dollar-substituting a $<.

@vindex gulam_help_file
@item gulam_help_file: none
set this var to the full pathname of the @code{gulam.hlp} file, which
contains descriptive info about keys, functions, bindings and
commands.  Unless this var is set properly, the wall chart that
@code{ue} generates is of not much use.

@vindex histfile
@item histfile: none
reads and saves history in file named $histfile .

@vindex history
@item history: 20
This variable controls the number of previous commands displayed
by the command @code{history}.

@vindex home
@vindex HOME
@item home
@itemx HOME: full pathname of home directory
home  is  the directory you were in before invoking @emph{Gul@"am}.  

@vindex mscursor
@item mscursor: unset
set it to a string of 4 digits (e.g., "0508").  This
controls the scaling of mouse movements being turned into cursor keys.  If
it is set to "0000", mouse movements do not get translated to cursor keys.


@vindex ncmd
@item ncmd: number  of  the  current  command
gets  set  after each executing each command.  

@vindex nrows
@item nrows: unset
This variable controls the number of lines per screen.  At present, only
valid values are 25 or 50.  Changing @code{nrows} to 50 will cause the
re-initialization of the screen using the small system font.

@vindex path
@vindex PATH
@item path: unset
when set, it will cause the environment variable PATH to be
automatically also set to the same string ($path), and cause
rehashing.

@vindex parent_expand
@item parent_expand: unset
when set, the Tenex name completion will provide the full path name rather
than just the leaf name.
@end table

The following pr_XXX vars are relevant with @code{print}, and @code{lpr}
commands.  When set, these strings are sent to the printer :

@table @code
@vindex pr_bof
@item pr_bof: unset
send before printing each new file.
@vindex pr_eol 
@item pr_eol: @ctrl{Q}r@ctrl{Q}n
send after each line.
@vindex pr_eop
@item pr_eop:@ctrl{Q}214
send after each page (214 == ASCII @ctrl{L} + 0200). 
@vindex pr_eof
@item pr_eof: @ctrl{Q}214
send after the end of file.  
@end table

Thus, to have a left margin of eight-spaces, just define @code{pr_eol} as
@kbd{@ctrl{Q}r@ctrl{Q}n@ctrl{Q}t}.  To turn condensed mode etc., just set
@code{pr_bof} to the appropriate string after looking it up in the
printer's manual.  See the section on strings for an explanation of
@ctrl{Q}.

@table @code
@vindex prompt 
@item prompt: >>
see gulam.g for an example.
@vindex prompt_tail
@item prompt_tail: unset;
when set,   $prompt_tail  is  appended  to  the  displayed  prompt
string.   This is a kludge to mollify those of you who insist
on having a trailing blank in their prompt! 
@vindex rgb
@vindex RGB
@item rgb
@itemx RGB: @code{000-700-007-070-}
sets  the  palette:  3 octal digits (followed by a  dummy  '-')  per
color;  2  in  hi-rez,  4  in med-rez, 16 in low-rez.
@vindex rx_remote_cmd
@item rx_remote_cmd: unset
command  to  send  to remote to receive file
with  Xmodem.   For  our  Unix, this string is `xm st'.  The rx
command  appends  a space followed by the file name and sends
the resulting string to the remote as if you typed it.  
@vindex sx_remote_cmd
@item sx_remote_cmd: unset
command to send to remote to send file with Xmodem.  Similar to the above.  
@vindex semicolon_max
@item semicolon_max: 20
Number  of @code{;} per line; to stop infinite recursions in alias expanded
commands.
@vindex status
@item status
status  of  the  most  recent external command; set after each external
command.
@vindex sz_rs232_buffer
@item sz_rs232_buffer: unset
The  built-in  terminal  emulator,  when invoked,  will  reallocate  a
buffer  of  this size (if this value  is  >  256) for the associated IOREC.
If unset, or if set  but  to  a  value  lower  than  4096, you may experience
XON/XOFF occuring at 9600.  I recommend 4096.
@vindex time
@item time: unset
If set to non-0, times every command.  
@vindex verbosity
@item verbosity: unset
This controls the amount of feed back you get from @emph{Gul@"am}.  When
unset, or set to <= 0, @emph{Gul@"am} will be extremely quiet, and report
only on errors.  If you wish commands like @code{cp} to report the
goings-on, set verbosity to 2.
@end table

@unnumberedsubsec HELP

The all-upper case name @kbd{HELP} in this manual stands for the key marked
@kbd{HELP} on the Atari ST.  Pressing this key, outside the @code{ue}, will
show all the @emph{Gul@"am} built-in commands, and a brief version of the
hash table.  Within @code{ue}, it can show the binding of an individual
key, or produce a wall-chart of all bindings.

The @kbd{shift-HELP} key resets the special key table mapping that Gulam/uE
use; after pressing @code{shift-HELP} the function keys, and arrow keys
become equivalent to @kbd{@ctrl{@@}}, and the keypad will work as a typcial
numerical keypad.  To get back to the Gulam/uE key table, press
@kbd{@ctrl{L}}, which not only refreshes the display but also sets the key
table.

@findex help
@node help,history,grep,Glossary
@unnumberedsubsec help

Typing the letters @code{help} while outside @code{ue}, or in buffer
@emph{gul@"am} is equivalent to pressing @kbd{HELP}.

@findex history
@node history,if,help,Glossary
@unnumberedsubsec history
@example
history [-h]
@end example

The @code{history} command lists the last N commands.  Each command is
preceded by its number; to suppress these numbers, supply the @code{-h}
flag.  The value N is obtained by @code{$history}.  To change this N to,
say, 30, do @code{set history 30}.

@node history-substitutions,io-redirection,flags,top
@unnumberedsubsec History Substitutions

Occurrences of the form @code{!!}, @code{!number}, @code{!string} refer to
the text of previously issued commands.  The text of these older commands
itself does not contain @code{!} unless it is part of a string argument.
Each @code{!!} is replaced by the text of the immediately preceding
command.  @emph{Gul@"am} consecutively numbers the commands that you have
issued.  (The current count can be seen in the shell variable named
@var{ncmd}.) Each @code{!n} is replaced by the
n-th  old  command.   Each  @code{!str} is a replaced by the most recent
old command that begins with str.  

The name completion feature works with history substitutions also.
Pressing @kbd{INSERT} or @kbd{ESC-ESC} will bring the history-matched
command and replace the current line in the buffer, which you can further
edit.

@vindex home
@vindex HOME
@unnumberedsubsec $home also $HOME

The shell variable @dfn{home} is initially set to the full pathname of the
directory from which @emph{Gul@"am} was invoked.  However, it can be set
again with set command to whatever.  The wiggle @code{~} in file
names expands to @dfn{$HOME}.  

@findex if
@node if,lpr,history,Glossary
@unnumberedsubsec if

The @dfn{if} stmt is similar to those in many programming languages.  The
Boolean expression of shell if stmts typically involves tests on file names
and types.  (See Expressions.) There is no @code{then}.  Any remaining
lexemes after the Boolean exp are ignored.

@example
if @{-d e:\gulam\lex@} + 2 == 3 
        echo e:\gulam\lex is a dir 
ef -e e:\gulam\lex      # read ef as `else if' 
        echo e:\gulam\lex does exist 
ef 
        echo e:\gulam\lex does NOT exist 
endif 
@end example

@node io-redirection,metacharacter-expansion,history-substitutions,top
@unnumberedsubsec IO Redirection

Prefixing a file name @var{f} with @code{>} causes all standard output
produced by that command to get deposited into file @var{f}.  Similarly,
@code{<g} will cause standard input to be taken from the file @var{g}
rather than the key board.  If you prefer, you may include white chars
between the @code{<} (or @code{>} ) and the filename.  If you have more
than one @code{<}, or @code{>} in a command all but the last are ignored.

Note that because of TOS and compiler peculiarities, not all external
commands will behave as above.

@example
ls -l > lsout # get the ls -l output into file lsout
ls -l >> f1   # append the ls -l output to f1
ecmd '>blah'  # invoke ecmd and give it the arg >blah as is to it.  
@end example

@findex kb
@node kb,lpr,if,Glossary
@unnumberedsubsec kb

This command redefines microEmacs keybindings.  To bind key with code 144
to function with hex-number 1d while you are in the @emph{regular} buffer,
do

@example
kb -r 144 1d      
@end example

Use -g for redefining the bindings of @emph{gul@"am} buffer; -m for mini
buffer.  You can find the key codes and hex-numbers of functions in the
wall-chart (shown below), which can be produced by pressing the @kbd{HELP}
key, a @kbd{B}, and then a @kbd{r} (or @kbd{g}, or @kbd{m}).  The key
names, and function names will not appear unless a @code{set
gulam_help_file <filename>} was done earlier.

@example
key-code in hex
|    function code in hex
|    |    key name (kb ignores this)
|    |    |         function name (kb ignores this)
---------------------------------------------------
081  5c   F1         kill-backward-word
082  5d   F2         kill-word
083  20   F3         kill-line
084  35   F4         copy-region-as-kill
085  51   F5         kill-buffer
086  50   F6         list-buffers
087  4e   F7         switch-to-buffer
088  3f   F8         write-file
089  3d   F9         find-file
08a  3e   F10        save-buffer
08b  14   HELP       help
08c  0d   UNDO       quick-exit
08d  62   INSERT     scroll-down
08e  61   HOME       scroll-up
0bb  23   UPARRO     previous-line
0bc  0f   DNARRO     gulam-forward-line
0bd  1a   LTARRO     backward-char
0be  1b   RTARRO     forward-char
140  30   C-@@       set-mark-command
141  1e   C-A        beginning-of-line
142  1a   C-B        backward-char
143  06   C-C        switch-to-gulam-buffer
144  1d   C-D        delete-char
145  1f   C-E        goto-end-of-line
146  1b   C-F        forward-char
147  13   C-G        keyboard-quit
148  1c   C-H        backward-delete-char
149  11   TAB        goto-next-tab
14a  25   LFD        newline-and-indent
14b  20   C-K        kill-line
14c  19   C-L        redraw-display
14d  10   RET        gulam-do-newline
14e  0f   C-N        gulam-forward-line
14f  22   C-O        open-line
150  23   C-P        previous-line
151  33   C-Q        quoted-insert
152  2b   C-R        search-backward
153  2c   C-S        search-forward
154  34   C-T        transpose-chars
156  61   C-V        scroll-up
157  36   C-W        kill-region
159  3b   C-Y        yank
15a  0e   C-Z        temporary-exit
15f  14   C-_        help
029  6b   )          blink-matching-paren-hack
07d  6b   @}         blink-matching-paren-hack
05d  6b   ]          blink-matching-paren-hack
0c0  0c   KLP        move-window-dn
0c1  0b   KRP        move-window-up
0c7  4a   KSLASH     split-window-vertically
0c2  49   KSTAR      delete-other-windows
0c5  45   KMINUS     previous-window
0c3  44   KPLUS      next-window
0c4  17   KENTER     call-last-kbd-macro
0c6  26   KDOT       goto-line
0b0  0a   K0         terminal-emulator
0b7  55   K7         beginning-of-buffer
0b8  32   K8         recenter
0b9  54   K9         end-of-buffer
0b4  5a   K4         backward-word
0b5  23   K5         previous-line
0b6  5e   K6         forward-word
0b1  1e   K1         beginning-of-line
0b2  0f   K2         gulam-forward-line
0b3  1f   K3         goto-end-of-line
541  09   C-X C-A    show-key-board-macro
542  50   C-X C-B    list-buffers
543  12   C-X C-C    save-buffers-kill-emacs
546  3d   C-X C-F    find-file
549  4d   C-X TAB    insert-buffer
54f  41   C-X C-O    delete-blank-lines
54e  0c   C-X C-N    move-window-dn
550  0b   C-X C-P    move-window-up
552  08   C-X C-R    read-file
553  3e   C-X C-S    save-buffer
556  3d   C-X C-V    find-file
557  3f   C-X C-W    write-file
558  42   C-X C-X    exchange-point-and-mark
55a  46   C-X C-Z    shrink-window
421  27   C-X !      execute-one-Gulam-command
421  07   C-X !      execute-buffer
43d  43   C-X =      what-cursor-position
428  15   C-X (      start-kbd-macro
429  16   C-X )      end-kbd-macro
431  49   C-X 1      delete-other-windows
432  4a   C-X 2      split-window-vertically
442  4e   C-X B      switch-to-buffer
445  17   C-X E      call-last-kbd-macro
446  18   C-X F      no-op
449  3c   C-X I      file-insert
44b  51   C-X K      kill-buffer
44e  44   C-X N      next-window
44f  44   C-X O      next-window
450  45   C-X P      previous-window
453  52   C-X S      save-some-buffers
45a  47   C-X Z      enlarge-window
348  5c   ESC C-H    kill-backward-word
221  07   ESC !      execute-buffer
22e  30   ESC .      set-mark-command
23e  54   ESC >      end-of-buffer
23c  55   ESC <      beginning-of-buffer
25b  56   ESC [      beginning-of-paragraph
25d  57   ESC ]      end-of-paragraph
225  2f   ESC %      query-replace
220  59   ESC SPC    just-one-space
242  5a   ESC B      backward-word
243  5b   ESC C      capitalize-word
244  5d   ESC D      kill-word
246  5e   ESC F      forward-word
247  06   ESC G      switch-to-gulam-buffer
24c  5f   ESC L      downcase-word
251  29   ESC Q      fill-paragraph
252  2b   ESC R      search-backward
253  2c   ESC S      search-forward
255  60   ESC U      upcase-word
256  62   ESC V      scroll-down
257  35   ESC W      copy-region-as-kill
27f  5c   ESC DEL    kill-backward-word
35b  05   ESC ESC    expand-name-gulam-style
344  63   ESC C-D    expand-names-and-show-them
346  04   ESC C-F    file-name
07f  1c   DEL        backward-delete-char
0ab  37   SHIFT-HELP keys-reset
000  00   NUL        no-op
000  00   NUL        no-op
000  00   NUL        no-op
000  00   NUL        no-op
000  00   NUL        no-op
000  00   NUL        no-op
000  00   NUL        no-op
000  00   NUL        no-op
000  00   NUL        no-op
000  00   NUL        no-op
@end example

@findex lpr
@node lpr,ls,if,Glossary
@unnumberedsubsec lpr
@example
lpr @var{filenames}
@end example

The command @code{lpr} prints its files as-is, with no processing at the
end of lines.

@findex ls
@node ls,mem,lpr,Glossary
@unnumberedsubsec ls
@example
ls [-ltrRLF] @var{filenames} 
@end example

The @code{ls} (list files) command, with no arguments, prints the sorted
list of names of the files in the current directory.  It has a number of
useful flag arguments, and can also be given the names of directories as
arguments, in which case it lists the names of the files in these
directories.

If no flags are given, @code{ls} prints only the filenames.  The @code{-L}
causes a full-length line for each file giving its attributes, size,
creation date, and name.  The @code{-l} (small el) is the same as @code{-L}
except that the output is sorted by name.  The @code{-R} will cause the
subtrees of directories in the argument list of files to be traversed.  The
@code{-F} will append to each listed filename one char that indicates the
type of that file: @code{*} if it is executable (i.e., has an extension of
@code{.prg, .tos, .ttp}, or @code{.g}), a @code{\} if its is a directory, a
' ' otherwise.  The @code{-t} causes a sort by time of modification of the
files.  The @code{-r} reverses the chosen order of sorting.

@code{ls} always (even if @var{dir_cache} is 1)
updates the directory cache for the relevant directories.

@findex mem
@node mem,mkdir,ls,Glossary
@unnumberedsubsec mem

@code{mem} shows the list of free chunks of memory available.  It does
this by following lists starting at an (undocumented) TOS location
(@code{0x7e8e} for ROMS dated 04221987, @code{56ec} for older ROMS),
Because of the way @emph{Gul@"am} uses dynamically allocated memory,
the size of the largest free chunk fluctuates both up and down as
chunks get coalesced and split.

	@code{mem -a} shows not only the free list, but also GEMDOS list of
Malloc-ated chunks.

@node metacharacter-expansion,path,io-redirection,top
@unnumberedsubsec Metacharacter Expansion

The characters @code{!$()[]><~*?}, called @dfn{meta characters}, have
special meaning to @emph{Gul@"am}.  If it is necessary to embed these
characters in arguments to commands but without such special meaning, you
must enclose the argument in single-quotes.

Arguments (to built-in or external commands) that contain meta chars are
expanded as follows.  The @code{!} is expanded first; see History
Substitution.  After this, the meta chars @code{$()[]~*?} are expanded from
left-to-right.  See Dollar Substitution.  The wiggle @code{~} stands for
@code{$HOME}.  The remaining meta chars @code{()[]*?} are part of the
@dfn{fnmre} -- regular expressions for file names.  Fnmre are slightly
different from egrep's Regular Expressions.  An fnmre differs from re in
(1) `.' stands for itself; (2) `*' is matches zero or more arbitrary
characters.  Occurrences of an fnmre, outside of strings, are replaced by
the sorted blank-separated list of file names matching the fnmre; see also
File Names.

@findex mkdir
@node mkdir,mv,mem,Glossary
@unnumberedsubsec mkdir
@example
mkdir @var{names}
@end example

The @dfn{mkdir} command creates new directories with the arguments as their
names.

@unnumberedsubsec more

This is a built-in alias, if you will, to @code{ue -r}.

@findex mv
@node mv,mson,mkdir,Glossary
@unnumberedsubsec mv
@example
mv @var{filenames target-dir}
mv @var{filename1 filename2}
@end example

Moves files.  In the first form, any number of files may be moveed into the
destination directory; files in the target dir will have their original
names.  In the second form, only one file is moved, and the new one will be
named filename2.  On the Atari ST, moving files is accomplished by copying
and then deleting the source file unless it is the second form and both are
in the same directory.

@findex mson
@findex msoff
@node mson,peekw,mv,Glossary
@unnumberedsubsec mson/msoff

These commands enable/disable the mouse.  To make the mouse disappear
give the command  @code{msoff} and to make it re-appear again, give the
command @code{mson}.  Most GEM-based @code{.prg} programs use mouse, but do
not set it up themselves.  Some of these will hang if invoked from
@emph{Gul@"am}, which is no big deal; do @code{mson} and then try.

@emph{Gul@"am} makes use of the mouse in two effective ways.
(1) When in Gulam command mode, moving the mouse around
allows you to select among previous commands that you
have in your history.  You can edit these in the usual
way with @code{ue} like commands.
(2) When editing a buffer with @code{ue}, moving the mouse around
will move the cursor around the screen.

To modify the effect of the mouse, set the variable  @code{mscursor}
to a four digit number.  The command
@code{set mscursor 0508}
is equivalent to the default mouse action.  The command
@code{set mscursor 1016}
you will require twice as much movement of the mouse to get the
same effect on the screen, and
@code{set mscursor 0000}
will turn it off altogether.


@vindex PATH
@vindex path
@node path,query-search-replace,metacharacter-expansion,top
@unnumberedsubsec $path also $PATH

A comma-separated list (with no white chars) of directiries should be
the value of the environment variable @code{PATH}.  @code{PATH} can be
set independently by using @code{setenv}, however, it gets
automatically reset to the value of @code{path} every time you do a
@code{set path whatever}.  This value is used by @code{rehash}
command.  @code{rehash} scans the files in each directory looking for
executable files (by def, files with extensions of @code{.prg},
@code{.tos}, @code{.ttp}, or @code{.g}).  The leaf names and full
pathnames are entered into a hash table.  Typing the @code{help}
command (not the @kbd{HELP} key) will list the hash table in brief;
@code{which} command lists it in full.  @emph{Gul@"am} does NOT auto
rehash whenever @code{PATH} is changed, but does rehash whenever
@code{path} is changed.

@example
setenv PATH c:,c:\bin,d:\mwc\bin 
@end example

@findex peekw
@findex pokew
@node peekw,popd,mson,Glossary
@unnumberedsubsec peekw/pokew

@code{peekw} and @code{pokew} are similar to their namesakes in BASIC.  We
use privileged mode to alter/access any arbitrary location.  These commands
expect their arguments to be hex numbers, so do not begin the numbers with
@code{0x}, or @code{$}.  The pokew command should be used with care.

@example
peekw 420      # shows you what is at word at 0x420 
pokew 420 123E # sets word at 0x420 to 0x123E 
@end example

The primary use for these is to examine/alter the TOS variables.  Refer to
BIOS Hitch Hikers Guide, ST Internals, or some other documentation for a
full list of these locations.  Here are a few that I often found useful:

@code{420 memvalid} Normally contains 0x7520.  If you then press reset the
ST will do a `warm boot' (which leaves most reset survivable RAM disks to
be still alive).  If you want to cause a cold boot, @code{pokew} this
location to a zero.  (The other way is to power cycle.)

@code{42E} and @code{0x430 phystop} This pair of integers (a long) gives
the address of top of RAM.

@code{440 seekrate} contains a code for the seek rate of floppies: 0 means
6 msec, 1 means 12 msec, 2 means 2 msec, and 3 means 3 msec.

@code{444 fverify} If @code{pokew} to zero, disk writes are not verified; any
other value will.

@findex popd
@node popd,print,peekw,Glossary
@unnumberedsubsec popd

The @code{popd} command changes the shell's working directory to the one on
top of the directory stack.  Also, sets @code{cwd}, and @code{CWD}.

@findex print
@node print,printenv,popd,Glossary
@unnumberedsubsec print
@example
print @var{filenames}
@end example

The @code{print} command is used to prepare listings of the contents
of files with headers giving the name of the file and the date and
time at which the file was last modified.  Use the @code{date} command
to set the time and date of the system properly.

@findex printenv
@node printenv,pushd,print,Glossary
@unnumberedsubsec printenv

The @code{printenv} command is equivalent to @code{setenv} with no
arguments.

@vindex $prompt
@unnumberedsubsec $prompt

@emph{Gul@"am} prompts for input with the contents of this variable.  Set
it with the @code{set} command.

@example
set prompt      '$ncmd $cwd gu > $u' 
@end example

@findex pushd
@node pushd,pwd,printenv,Glossary
@unnumberedsubsec pushd
@example
pushd [@var{dir}]
@end example

The @code{pushd} (push directory) command pushes the name of the current
directory on to the internal stack, and @code{cd}'s to the directory given
by the argument.  You can later do a @code{popd} to return to the present
current directory.  The command @code{pushd}, without arguments, exchanges
the working directory with the one on top of the stack.

@findex pwd
@node pwd,rehash,pushd,Glossary
@unnumberedsubsec pwd

This built-in command prints the full pathname of the current working
directory.  It is equivalent to

@example
	echo $cwd
@end example

@node query-search-replace,regular-expressions,path,top
@unnumberedsubsec Query Search/Replace

The built-in @code{ue} uses regular expression search and replace; see
Regular Expressions.  This function is normally bound to @kbd{ESC-%}.  When
you invoke it, it will ask you to type the search pattern, and then the
replace pattern.  It then enters the search/replace mode: finds the next
(to the right, and below) occurrence of the search pattern, and awaits your
response.  You type
@enumerate
@item
a @kbd{SPACE} to replace the occurrence of the
search pattern
@item
a @kbd{DELETE} to skip to the next occurrence
@item
a dot (`.') to replace this one and then terminate search/replace
@item
@kbd{ESC} to end the search/replace right now, and
@item
an exclamation (`!') to replace this and all further occurrences without
bothering to ask you.
@end enumerate

If you forget all this, type an arbitrary key and you will get the brief
reminder:

@example
<SP>rplce, [.]rep-end, <DEL>dont, [!]repl rest, <ESC>quit
@end example

The only char that has a special meaning in the replace string is `&'; all
other meta-chars stand literally for themselves.  An `&' stands for the
substring that matched the whole regular expression.  A `\n', where n is a
digit in 1 to 9, stands for the substring that matched the n-th
parenthesized expression within the regular expression, with parenthesized
expressions
numbered in left-to-right order of their opening parentheses.  

Be aware of a peculiarity of the search/replace: The @code{^} and @code{$}
of the regular expression match the positions just right of the dot, and
just left of the dot.  Thus, if you give a search string of '@code{^}', and
replace string '@code{a}', and then issue a '@code{!}', you will be
inserting '@code{a}' forever (until @code{ue} runs out of memory).

@node regular-expressions,strings,query-search-replace,top
@unnumberedsubsec Regular Expressions

[This  section  is a mildly edited man page of regexp(3) by Henry
Spencer.] 

A  regular  expression  is  zero  or  more branches, separated by
`|'.  It matches anything that matches one of the branches.  

A  branch  is  zero  or  more pieces, concatenated.  It matches a
match for the first, followed by a match for the second, etc.  

A  piece  is  an  atom possibly followed by `*', `+', or `?'.  An
atom  followed  by `*' matches a sequence of 0 or more matches of
the  atom.   An  atom  followed by `+' matches a sequence of 1 or
more  matches  of  the  atom.   An atom followed by `?' matches a
match of the atom, or the null string.  

An  atom is a regular expression in parentheses (matching a match
for  the  regular expression), a range (see below), `.' (matching
any  single  character),  `^'  (matching  the  null string at the
beginning  of the input string), `$' (matching the null string at
the  end  of  the  input  string),  a  `e'  followed  by a single
character  (matching  that character), or a single character with
no other significance (matching that character).  

A  range  is  a  sequence  of  characters  enclosed  in `[]'.  It
normally  matches any single character from the sequence.  If the
sequence  begins  with  `^',  it matches any single character not
from  the  rest  of  the  sequence.   If  two  characters  in the
sequence  are  separated  by  `-', this is shorthand for the full
list  of  ASCII characters between them (e.g. `[0-9]' matches any
decimal  digit).   To include a literal `]' in the sequence, make
it  the first character (following a possible `^').  To include a
literal `-', make it the first or last character.  

If  a  regular  expression could match two different parts of the
input  string,  it  will match the one which begins earliest.  If
both  begin  in  the  same  place but match different lengths, or
match  the  same  length in different ways, life gets messier, as
follows.  

In   general,  the  possibilities  in  a  list  of  branches  are
considered  in  left-to-right  order,  the possibilities for `*',
`+',  and `?' are considered longest-first, nested constructs are
considered  from  the  outermost  in, and concatenated constructs
are  considered leftmost-first.  The match that will be chosen is
the  one  that  uses the earliest possibility in the first choice
that  has to be made.  If there is more than one choice, the next
will  be  made  in the same manner (earliest possibility) subject
to the decision on the first choice.  And so forth.  

For  example,  `(ab|a)b*c'  could match `abc' in one of two ways.
The  first choice is between `ab' and `a'; since `ab' is earlier,
and  does  lead  to  a  successful  overall  match, it is chosen.
Since  the  `b'  is  already  spoken for, the `b*' must match its
last  possibility  the  empty  string  since  it must respect the
earlier choice.  

In  the  particular  case  where no `|'s are present and there is
only  one  `*',  `+',  or `?', the net effect is that the longest
possible   match  will  be  chosen.   So  `ab*',  presented  with
`xabbbby',  will  match  `abbbb'.   Note  that  if `ab*' is tried
against  `xabyabbbz',  it  will match `ab' just after `x', due to
the  begins-earliest  rule.  (In effect, the decision on where to
start  the match is the first choice to be made, hence subsequent
choices   must   respect   it   even   if   this  leads  them  to
less-preferred alternatives.) 

Here are some examples of usage: 

@example
ls *[sg]        # print file names ending in s or g
egrep '(MWC|MEGAMAX|MANX)' *.c       
egrep '^$' *.c  # print line numbers of empty lines
egrep 'aa*' *.c
@end example

@findex rehash
@node rehash,ren,pwd,Glossary
@unnumberedsubsec rehash

-- see PATH 

@findex ren
@node ren,rm,rehash,Glossary
@unnumberedsubsec ren
@example
ren @var{fnm1} @var{fnm2}
@end example

Rename file @var{fnm1} as @var{fnm2}; they both must be in the same
directory.

@findex rm
@node rm,ren,rx,Glossary
@unnumberedsubsec rm
@example
rm @var{filenames}
@end example

@code{rm} removes the named files.  Most of us have the following aliases
in our @code{gulam.g} files:

@example
alias rm rm -i 
alias Rm rm 
@end example

which queries you, for each file, before deleting it.  We use @code{Rm}
when we are really sure we want to delete the file(s).  There is
no  special check to see if you typed @code{rm *.*} or @code{rm *}; both of
these will clear your current directory.  

@findex rx
@findex sx
@node rx,set,rm,Glossary
@unnumberedsubsec rx/sx

These are built-in commands.  @code{rx} receives file(s) from the remote
system; and @code{sx} sends file(s) to the remote system using Xmodem
protocol.

@example
rx @var{fnm}
@end example

command opens/creates file @var{fnm} for writing.  If the shell variable
@code{rx_remote_cmd} is set, @emph{Gul@"am} constructs a command for the
remote system as @code{$rx_remote_cmd} @var{fnm}, and sends this command
through the rs232 port, and then awaits the packets.  For use with our
4xBSD Unix, we set this var to @code{xm st}.  Unless the @code{xm} on the
remote machine is of the quiet type (one that does not respond with, say,
@code{Xmodem: Ready to send...}), setting @code{rx_remote_cmd} actually
prolongs the first synchronization.  If this var is unset, you should first
switch to remote (say using te command), and issue the appropriate command
to the remote, and then switch back to AtariST and give the @code{rx}
@var{fnm} command.

@example
sx @var{fnm}
@end example

is essentially similar.  @emph{Gul@"am} opens @var{fnm} for reading, sends@*
@code{$sx_remote_cmd} @var{fnm}, if that var is set, and awaits the first
sync.  For our 4xBSD Unix, we set @code{sx_remote_cmd} to @code{xm rt}.

	If sending/receiving binary files use @code{xm rb} or @code{xm
sb} as the remote system's commands.  Note that files received with
Xmodem usually contain extraneous bytes at the very end of the file.
With text files, you often see a bunch of @kbd{@ctrl{Z}}s.

	When both @code{sx_remote_cmd} and @code{rx_remote_cmd} are set
appropriately, it is possible to transfers of batches of files.  For example,

@example
sx @var{d1/d2/f1 d1/f2}
@end example

will invoke @code{xm rt} on the far end and send file @code{d1/d2/f1},
and after this is finished invoke @code{xm rt} once again and send the
second file @code{d1/f2}.  The @code{rx} command also can smilarly
take multiple arguments.

@findex set
@node set,setenv,rx,Glossary
@unnumberedsubsec set
@example
set [@var{name} @var{value}]
@end example

The built-in @code{set} command is used to assign new values to shell
variables and to show the values of the current variables.  The command
without any arguments lists all the shell vars and their values.  When
arguments are present, second and subsequent words are processed as an
expression yielding a value which is then assigned to the first argument.
The @code{unset} command deletes a variable.

@example
set i  @{$j > 10 @} # sets i to 1 if $j is > 10; else to 0
set x "hi there" 
set y $i + 4 @@ 2   # @@ stands for multiplication 
@end example

@findex setenv
@node setenv,source,set,Glossary
@unnumberedsubsec setenv

Variables in the environment can be changed by using the @code{setenv}
built-in command.  The @code{setenv} command without args prints the values
of all the variables in the environment.

@findex source
@node source,te,setenv,Glossary
@unnumberedsubsec source
@example
source @var{file-name}
@end example

The contents of file @var{file-name} are excuted by @emph{Gul@"am}.
Unless the @var{file-name} has an extension other than @code{.g}, use
the simpler command @code{file.g} instead.

@vindex status
@unnumberedsubsec status

A command normally returns a status when it finishes.  By convention a
status of zero indicates that the command succeeded, and @emph{Gul@"am}
does not show this value.  Commands may return non-zero status, whic is
displayed, to indicate that some abnormal event has occurred.  The shell
variable status is set to the status returned by the last command.

@node strings,file-name-completion,regular-expressions,top
@unnumberedsubsec Strings

Strings are the most common data type that shells deal with.  In
@emph{Gul@"am}, unless otherwise stated, all operands are considered to be
strings.  There are a few occasions when it is necessary to suppress the
typical string preprocessing such as meta-char expansion.  Such strings are
enclosed in single-quotes.  A string enclosed in double quotes is dollar-,
and meta-expanded, and then enclosed in double quotes.  Try, @code{echo
*.c} and @code{echo '*.c'} in a directory that has a few files with the
@code{.c} extension.  Within a quoted-string, you can include control
characters by inserting a @kbd{@ctrl{Q}} (control-Q) followed by the octal
ASCII code (always using 3 digits) of the character; see the @code{gulam.g}
section for examples.  In general, if you want to set a var to a string
that contains control-chars, first write it out in the C language notation,
and replace each back-slash with a @kbd{control-Q}.

@findex te
@findex teexit
@node te,time,source,Glossary
@unnumberedsubsec te/teexit

@code{te} (also  bound to @kbd{Keypad-0}) gets you into the built-in terminal
emulator.   If  you have baud_rate set up properly (see gulam.g),
the  rs232  port  is set to that speed, and you are switched to a
fresh  screen.   Set  @code{sz_rs232_buffer}  to  a  large  value if you
encounter  XON/XOFF  problems  too frequently.  We have  used the
following  TERMCAP  and  used  vi,  GNU-Emacs  etc  without  any
problems.  

@example
st|st25|atariST|bw, std sys font, 25 lines, 80 col:
   :ae=Eba:al=EL:am:as=Ebc:
   :bl=^G:bs:
   :cd=EJ:ce=EK:cl=EHEJ:cm=EY%+ %+ :co#80:cr=^M:
   :dl=EM:do=EB:
   :ho=EH:
   :is=EvEe:
   :kd=274:kh=216:kl=275:kr=276:ku=273:
   :le=^H:li#25:
   :nd=EC:nl=^J:
   :pt:
   :se=Eq:so=Ep:sr=EI:
   :ta=^I:
   :up=EA:


ST|ST25|atariSTcolor|as above but with color for stndout:
   :ae=Eba:al=EL:am:as=Ebc:
   :bl=^G:bs:
   :cm=EY%+ %+ :co#80:li#25:cr=^M:cd=EJ:ce=EK:cl=EHEJ:
   :dl=EM:do=^J:
   :ho=EH:
   :is=EvEe:
   :kd=274:kh=216:kl=275:kr=276:ku=273:
   :le=^H:
   :nd=EC:nl=^J:
   :pt:
   :so=Ec2Eb3:se=Ec0Eb3:sr:EI:
   :ta=^I:
   :up=EA:

sT|st50|AtariST emulating vt52, bw, 50 lines, 80 col:
   :ae=Eba:al=EL:am:as=Ebc:
   :bl=^G:bs:
   :cd=EJ:ce=EK:cl=EHEJ:cm=EY%+ %+ :co#80:cr=^M:
   :dl=EM:do=^J:
   :ho=EH:
   :is=EvEe:
   :kd=274:kh=216:kl=275:kr=276:ku=273:
   :le=^H:li#50:
   :nd=EC:nl=^J:
   :pt:
   :se=Eq:so=Ep:sr=EI:
   :ta=^I:
   :up=EA:
@end example

To return to the local mode after having done @code{te}, press @kbd{UNDO}.
Then a @kbd{Keypad-0} will take you back to remote with your remote screen
in tact.  After you are finally done with your remote system, press
@kbd{UNDO}, and then issue a @code{teexit} to reclaim the 32k used for the
extra screen.

@node file-name-completion,,strings,top
@unnumberedsubsec Tenex File Name Completion

Tenex is widely considered to be the first OS to implement the completion
of a file's name given the first few chars of it.  Experiment with the keys
marked @kbd{INSERT}, @kbd{TAB} and @kbd{CLR/HOME}, while you are in
@emph{mini}.  If you are in buffer @emph{gul@"am}, use @kbd{ESC-ESC} (2
escapes).  See File Names.

@findex time
@node time,touch,te,Glossary
@unnumberedsubsec time

The word @code{time} when prefixed to a regular command, it prints the
elapsed time after the command finishes.  If you set variable
named @code{time}  to  a non-zero value, each and every command, even
if  they  are  not  prefixed  with  the  word @code{time},  will be so
timed.  

@example
time  ls -lF c:\        # See how long it takes 
set   time  1           # After this, all command will be timed until 
set   time 0            # you do this, or 
unset time              # this 
@end example

If you set up aliases with @code{time} prefixes in them, watch out!  The
discussion under the section on Gem is applicable to @code{time} also.

@findex touch
@node touch,ue,time,Glossary
@unnumberedsubsec touch
@example
touch @var{fnms}
@end example

@code{touch}  updates  the  time  stamp on the files to current time and
date.  

@findex ue
@node ue,uekb,touch,Glossary
@unnumberedsubsec ue
@example
ue [-r] [@var{fnms}]
@end example

This command takes you into the built-in microEmacs editor.  If
no  args  are  given,  you  will  land  in  the  @emph{gul@"am}  buffer,
otherwise in the buffer of the last named file.  The output of
@emph{Gul@"am} commands executed while you are within @emph{gul@"am} is
entered into that buffer; this, of course, consumes malloc-space.
@kbd{Meta-g} brings you into @emph{gul@"am} if you are in another buffer.

To examine the key bindings, press @kbd{HELP}-key first, and then a @kbd{B}
while inside @code{ue}.  To rebind them to suit your tastes, see @code{kb}.
On the Atari ST, all the keys are bound (thoughtfully, I hope) to useful
commands.  @kbd{F1} through @kbd{F5} delete things; @kbd{F6-F10} update
files and buffers; Keypad keys cause harmless cursor motions; @kbd{Keypad
0} (zero) switches you to the (remote computer hooked to the) rs232 port;
to return to your local Atari, press @kbd{UNDO}.  @kbd{HELP} is for (not
much) help; @kbd{UNDO} will exit after saving files; the rest of the keys
in that group move the cursor around.

The @code{-r} flag causes the buffers of the files following the @code{-r}
to be marked as read-Only.  You can still edit these buffers; but the
read-Only mark causes @code{ue} to ask before writing to these files.

Do try @kbd{@ctrl{Z}, @ctrl{X}-!} and @kbd{Meta-X-!} commands.  

@findex uekb
@node uekb,unalias,ue,Glossary
@unnumberedsubsec uekb

The command @code{uekb} has been renamed as @code{kb}.

@findex unalias
@node unalias,unset,uekb,Glossary
@unnumberedsubsec unalias
@example
unalias [@var{aliassed-name}]
@end example

The unalias command removes aliases.   

@findex unset
@findex unsetenv
@node unset,which,unlalias,Glossary
@unnumberedsubsec unset unsetenv
@example
unset [@var{var-name}]
unsetenv [@var{env-var}]
@end example

The unset command removes the definitions of shell variables.  

@unnumberedsubsec variables

See also: @emph{Gul@"am} Vars and Environment; Dollar Subst.  

A variable name is any sequence of characters not containing delimiters.  A
Variable in @emph{Gul@"am} holds a string as its value.  Depending on the
context this string is evaluated to yield a numeric value.

@findex which
@node which,while,unset,Glossary
@unnumberedsubsec which

The @code{which} command displays the internal table of names of external
commands, and the full pathnames of the files that contain them.  If
nothing  gets  displayed,  either  you did not do a @code{rehash}, did
not  setenv  the PATH, or none of the directories in PATH had any
executables.  

@findex while
@node while,,which,Glossary
@unnumberedsubsec while

The @code{while} built-in control construct is used in shell command
scripts.  Instead of echo and set in the body of the loop shown below, you
can use other commands.

@example
set i 10 
while  @{ $i >  0 @} 
      echo $i 
      set i $i - 1 
endwhile 
@end example

@node Variables Index, Command Index, top, top
@unnumbered Variable Index

@printindex vr

@node Command Index,,Variables Index, top
@unnumbered Command Index

@printindex fn

@contents

@bye
